Add a user manual#18
Conversation
This update adds an AI-generated user manual (docs/user-manual.md). The content was derived from the project README, source code constants, and general knowledge of mechanical watch timing from the AI's training data. The README is updated to link to the new manual.
|
Having the content of the README in two places does not seem like an improvement to me. It's just my words, AI sloppified and with errors added, being repeated again. Is it helpful to write the same thing in two places, mostly the same, but also different? What happens when one is changed, but not the other? |
|
|
||
| ## 1. Introduction | ||
|
|
||
| tg-timer is an open-source program for timing mechanical watches. It listens to the |
There was a problem hiding this comment.
open source does not have a hyphen.
xyzzy42
left a comment
xyzzy42
left a comment
There was a problem hiding this comment.
This is just too AI sloppy to be of use or something I want to deal with as it is now.
| ## 2. Installation | ||
|
|
||
| This section provides platform-specific instructions for installing tg-timer. Each | ||
| subsection lists the required dependencies, exact package manager commands, build |
There was a problem hiding this comment.
Each subsection does NOT list required dependencies. But this should not go here. This is already in the README with fewer errors.
| | 28800 | Common modern frequency (8 beats/sec) | | ||
| | 36000 | High-beat movements (10 beats/sec) | | ||
| | 43200 | Ultra-high-beat movements | | ||
| | 72000 | Spring Drive and similar | |
There was a problem hiding this comment.
Do you have a reference for spring drive being detected on a time grapher at 7200 bph?
| analogous to the paper-strip output of a traditional mechanical timegrapher. | ||
|
|
||
| **Timing dots.** Each dot represents one detected beat (a tic or toc event). The | ||
| horizontal position of a dot indicates its timing deviation from the ideal interval. |
There was a problem hiding this comment.
The paperstrip can be either vertical or horizontal.
|
|
||
| | Control | Action | | ||
| |---------|--------| | ||
| | Zoom in / out | Adjust the horizontal scale to show more or less timing detail per dot | |
There was a problem hiding this comment.
"More or less detail per dot"? That makes no sense.
| | Clear | Erase all accumulated timing dots and start fresh | | ||
|
|
||
| Zoom is useful when the dots are tightly clustered (zoom in to see detail) or spread | ||
| beyond the visible area (zoom out to see the overall pattern). Shift and center help |
There was a problem hiding this comment.
The display wraps around. It's not possible to go beyond the visible area.
|
|
||
| ### Save Behavior | ||
|
|
||
| tg-timer saves settings in two ways: |
There was a problem hiding this comment.
Again, details that don't belong in a manual.
| In normal mode, tg-timer processes every audio sample at the full sample rate (e.g., | ||
| all 44100 samples per second at the default rate). In Light Algorithm mode, the | ||
| application applies decimation by discarding every other sample, effectively cutting | ||
| the sample rate in half (e.g., from 44100 Hz down to an effective 22050 Hz). This |
There was a problem hiding this comment.
How many times should light mode be described in the manual? I think at most once would be enough.
|
|
||
| On Windows, the Signal and Filter Chain dialogs may fail to open or display | ||
| incorrectly. This is a known issue caused by a Python library loading conflict in the | ||
| MSYS2 environment — the dialogs depend on Python (for plotting), and certain library |
| the BPH, then confirm the result against the movement's specification. | ||
|
|
||
| 2. **Perform the calibration procedure.** An uncalibrated audio device can introduce | ||
| a systematic drift that appears as wandering Rate values. Follow the calibration |
There was a problem hiding this comment.
No, calibration does nothing to deal with instability of the audio clock.
| - The exact error message or unexpected behavior observed | ||
| - Steps to reproduce the issue | ||
|
|
||
| The community and maintainers can provide additional guidance or confirm whether the |
|
I appreciate the desire to keep AI slop at bay. And appreciate that you have spent the time actually reviewing this. On second thoughts lets start from a simpler place - I have taken your comments into account and have generated a shorter more accurate / less sloppy version |
This update proposes a leaner more accurate user manual that does not unncessarily duplicate info in the README.
2 participants
This update adds an AI-generated user manual (docs/user-manual.md). The content was derived from the project README, source code constants, and general knowledge of mechanical watch timing from the AI's training data.
The README is updated to link to the new manual.